Digital input and digital output are electrical contacts (connector pins) that are energized by the voltage of only two levels: one of them corresponds to the on-state (1, or On), and the other one — to the off-state (0, or Off). Hence, digital inputs and outputs are used to connect tracker and devices or circuits that transmit only two possible states. For example, you can connect a door status sensor to the tracker's digital input so that the tracker can determine whether the door is open or not. And you can connect an anti-theft device to the tracker's digital output that will be controlled by the tracker and block the ignition.

I should note that if the client requires an exact numerical value, an analog connector is needed. Because if you, for example, use a digital input for FLS, you can only find out whether there is fuel in the tank or not.

The number of digital inputs and outputs on the tracker may be quite large (for example, Galileosky 7x may have from 6 to 10 digital inputs, depending on modification and configuration). Therefore, users often wonder to which digital input or output the installer connected the device a client is interested in. Follow the instructions below to get the answer.

Displaying digital inputs/outputs

At first, it should be noted that the state of digital inputs and outputs in Wialon is represented as two hexadecimal numbers (HEX) obtained from binary numbers (BIN), in which each bit corresponds to an input/output with the same number. The parameter with these values is named I/O (short for Inputs/Outputs) and contains two numbers separated by a slash: to the left, there is the value corresponding to the state of all inputs, and to the right — the state of the outputs.

Why was this implementation chosen? Let's look at an example.

Suppose that some vehicle attachments are connected to digital inputs 1, 3, 4 and 7 and outputs 1, 3, 6 and 8. Also, suppose that all the mentioned inputs and outputs are activated in the considered message. If separate parameters were used for each of them in the message, you would see the following:

in1=1, in2=0, in3=1, in4=1, in5=0, in6=0, in7=1, in8=0, out1=1, out2=0, out3=1, out4=0, out5=0, out6=1, out7=0, out8=1

In the current implementation in Wialon, you will see the following entry:

I/O=4D/A5

The obvious conciseness of the entry is a key advantage.

Defining the number of an activated digital input/output

If the number N of an input or output is known, the corresponding parameter will be inN, and the output parameter will be outN. For example, the parameter for the fourth input is in4 and for the output — out4.

However, if you don't know the number of an input or output to which the hardware is connected, you can use one of two methods: selection or a mathematical approach.

Selection

When connecting hardware, installers most often use the first inputs/outputs. So, if we talk about a device or circuit that transmits information to the tracker, you should check in1-in4, and if it's about a device or circuit that the tracker controls — out1-out4.

To find the needed input, you can create 4 sensors with the Custom digital sensor type based on these parameters (for example, the first sensor will have in1 in the Parameter field, the second — in2, and so on). Then go to the Messages panel, select the Data Messages type, and specify Sensor values ​​in the menu below. After that, query messages for the interval when the hardware was first turned off and then turned on to find the moment of transition from Off to On in one of the columns, each of which corresponds to the created sensor.

This is the fastest practical way to find the needed input (similarly, you can work with outputs, but in this case, you should use the parameters out1, out2, and so on). If it doesn't work, you can use a mathematical approach.

Mathematical approach

If you don't know the number of an input/output to which the hardware is connected, you can use the following instructions:

1. Go to the Messages panel, select the Data Messages type, and specify Raw data in the menu below.
2. Query messages for the interval when the hardware was first turned off and then turned on.
3. After displaying the table with messages from the tracker, pay attention to the Parameters column and find the I/O parameter there (it's located at the very end of the line).
   
   Suppose that the message where the hardware was turned off has the I/O=102/0 parameter, meaning that digital outputs are deactivated (or not even connected), and some digital inputs are activated.
   
   
4. Open the Calculator application (it is preinstalled on every computer, or you can find its analogs on the internet) and switch it to the Programming mode (or a similar one that allows you to convert values from one numeral system to another).
5. Switch the calculator to a hexadecimal numeral system (HEX).
6. Enter the value 102 found earlier.
7. The application will automatically (or by pressing the enter key) show you the given number in different numeral systems. We need the binary format entry (BIN), which consists only of zeros and ones.
   
   
   
   
8. Examine the resulting binary number. Note that the bit number is counted from right to left (as in the decimal system, where ones are to the right, tens are to the left of them, then hundreds, thousands, and so on): 0001 0000 0010

9. Determine the bit numbers for a given number (bit numbering in Wialon starts from 1):

   Number	12	11	10	9	8	7	6	5	4	3	2	1
   Value	0	0	0	1	0	0	0	0	0	0	1	0

10. From this entry, we can conclude that in this message, inputs 2 and 9 are activated (i.e., in2=1, in9=1), and all other inputs are deactivated (i.e., their value is zero).
11. Now find the message where the hardware was turned on. Suppose it contains the I/O=10A/0 parameter.
12. Repeat steps 4-8 for the 10A value.
    
    
    
    

13. Determine the bit numbers for a given number:
    

    Number	12	11	10	9	8	7	6	5	4	3	2	1
    Value	0	0	0	1	0	0	0	0	1	0	1	0

14. In this message, inputs 2, 4 and 9 are activated (i.e., in2=1, in4=1 and in9=1).
15. Compare the results of steps 10 and 14. As you can see, they differ only in the state of the in4 parameter, which means the hardware in the given example was connected to input 4.

Using digital inputs/outputs

You can use the digital input or output parameter the same way as any other parameter.

When creating sensors for digital inputs/outputs, types from the Digital group are most suitable since they imply only two states (On and Off).

A unique use case, which is only available for digital inputs, is a notification with the Digital input type, for which you don't even need to create a sensor.

Oleg Zharkovsky,Customer Service Engineer 2022-02-03

One of the first and crucial stages of working with Wialon is setting up sensors in the unit. If the sensors are set up correctly, then some standard algorithms will give more accurate results and you will get access to functionality that has not been available before. The calculation table, a tool from the tab of the same name, is considered in detail in this article since this exact tool most often causes difficulties when setting up sensors.

General principle of sensors operation

Wialon supports many types of trackers; you can find their current number on the wialon.com website in the Hardware section. Each of the trackers "speaks" in its own way. Therefore, the parameters which come from different types of trackers and which are displayed on the Messages tab may contain the same information (for example, about temperature or mileage) but have different names. It is necessary to create sensors for each unit in Wialon to prevent users from noticing the differences when using units with various trackers. Also, sensors have a specific type, which allows the system to understand which algorithm to choose to process input values.

However, a simple selection of a sensor type and specifying a parameter in it is often not enough because the parameter value comes in an unobvious to the user way. For example, temp=125 could mean 125°F, 125°C, 12.5°C, or even -3°C. There are three methods to convert the input parameter to the desired type:

1. Expression in the Parameter field;
2. Calculation table;
3. Validation.

They can be used individually or combined. If you use several methods simultaneously, they will be applied in the exact order they are listed above.

Schematically, the use of sensors can be represented as follows:

• The sensor connected to the tracker measures some physical quantity; let’s denote it by S.
• The sensor converts this value and transmits it to the tracker. The X parameter comes from the tracker to Wialon.
  
• Based on the parameter, a sensor is created in Wialon. Then, f(X) transformations are applied to the parameter in the sensor to obtain a human-readable Y value.
  
• Ideally, after transformations in the sensor, the value Y=f(X) should be equal to the value S measured in the first stage. Further, Y will be used in tooltips, reports, notifications, and other Wialon functionality.
  

Since this article only explains the process of setting up the calculation table in Wialon, we will pay attention only to the following elements from the scheme above:

When to use a calculation table

Usually, the calculation table is used in cases where it is necessary to convert the input parameter. However, all three methods mentioned above serve to do this. In what scenario is it worth choosing the calculation table?

In terms of practical application, the calculation table might be used for:

• the calibration table (for example, for weight sensors or fuel level sensors);
  
  
• digital sensors based on analog input data (for example, ignition sensors based on voltage);
  
  
• sensors based on codes that describe different states but come in one parameter (for example, device_status=4 means the ignition is on, and device_status=13 means the panic button is pressed, etc.);
  
  
• sensors that should display positive and negative values, although the parameter associated with them has only positive values (for example, for temperature sensors);
  
  
• any sensors in which it is necessary to separate the range of correct and erroneous values (for example, if the sensor sends specific values in a parameter that indicate errors).

Calculation table settings

The calculation table involves working with the simplest linear functions. That means that the calculation table converts the data in accordance with the Y=a⋅X+b formula — one of the variants of the straight-line equation.

If you understand how each component of this equation works, you can implement valuable and unusual solutions with its help. Next, we will review each area of the Calculation Table tab separately and visualize its impact on the result using a chart.

XY pairs

On the right side, you can see the XY pairs block. Filling it in is not enough for the calculation table to work, but it can simplify its settings.

You can add pairs manually or by importing CSV or TXT files (export is available in CSV only). After filling in all the fields of this block, you must click the Generate button (meaning, generate a calculation table based on XY pairs). This action will lead to the values of X, a, and b calculation in the left part of the window.

Each of the added XY pairs corresponds to a point on the chart. As you know, you can draw a line through two points. Therefore, if you enter five XY pairs, you will get four straight lines on the chart.

X is an input value

The central block of the Calculation Table tab contains rows with X, a, and b values. Each of the rows corresponds to a straight line on the chart. The value of X in each row means the beginning of a new straight line, that is, it sets the interval where new values of a and b will be used.

As an example, consider a table with the following values:

Otherwise, this condition can be written as follows:

• From −∞ to 3 (not including), the equation Y=1⋅X-2 is applied.
  
• From 3 (including) to 5.5 (not including), the equation Y=0⋅X+3 is applied.
  
• From 5.5 (including) to +∞, the equation Y=-0.5⋅X+2 is applied.
  

An example of a chart obtained when filling in the calculation table

a is a slope coefficient of the line

With a=0, the slope will be 0°; thus, the line will be parallel to the X-axis.
With a=1, the slope will be 45°; thus, the larger the coefficient, the closer the line will be to the Y-axis.
With a=-1, the slope will be −45 °; thus, negative values of this coefficient tilt the line down, and positive values — up.

An example of a chart of the Y=a⋅X line with different slope coefficients

b determines the displacement of the line along the Y-axis

When b=0, there is no displacement.
When b>0, the straight line is displaced upward relative to the X-axis.
When b<0, the displacement is downward.

An example of lines with different displacements

Lower and upper bounds

Lower and upper bounds allow you to cut off erroneous sensor values according to a simple principle — if the value is outside the range between the lower and upper bounds, the sensor will display a dash (error).

Let’s consider an example with a fuel level sensor. Assume that parameter values from 3 to 250 correspond to fuel volumes from 0 liters to 100 liters. And the 0 or 255 values of the parameter mean errors that we want to exclude so that they are not interpreted as a realistic volume since the tank in the example cannot have less than 0 or more than 100 liters of fuel. For this example, you can propose a solution with the Apply after calculation option turned off:

There is also a solution with the Apply after calculation option enabled:

From the example, you can see that the Apply after calculation option affects which values the bounds apply to: if it is off, then the system filters out the values along the X-axis (the input values before applying the calculation table), and if it is enabled, then it filters out the values along the Y-axis (sensor values after applying the calculation table).

To visualize how the bounds work, consider another example in which the same bounds applied to the same straight line and the difference lies only in the Apply after calculation option, which significantly affects the result.

The lower bound equals 2, the upper bound equals 3, the Apply after calculation option is disabled

The lower bound equals 2, the upper bound equals 3, the Apply after calculation option is enabled

The principle of the calculation table operation

Sometimes, to understand the essence of a phenomenon, it's better to go backward. If we know the precise formula Y=f(X), which relates the input and output values over the entire range, then there is no need to use the calculation table. It's better to use the expression in the Parameter field instead. Let's consider such a case.

Suppose that an input value is related to an output value by the Y=0.5⋅X² formula.
Let's take adc3 as a parameter. To describe such a formula in Wialon, insert the following expression into the Parameter field: const0.5*adc3^const2

The chart of the Y=0.5⋅X² function

But what if we don't know the precise Y=f(X) formula? In this exact case, the calculation table will help us.

Suppose that we know the values of the measured value (it will be Y), and we can check what value the parameter will take in Wialon at those points (it will be X). Thus, you can get values, for example, at four points: (0; 0), (1; 0.5), (2; 2), (3; 4.5). Next, plot these points (X, Y) on the chart and connect them with red lines.

Reproduction of a part of the function Y=0.5⋅X² by lines built on four points

It is easy to see that the result is close to that obtained by the formula, but there are still differences. In some cases, this accuracy will be sufficient, but if it is not enough, you can measure values ​​at more points. The chart below shows an example for six points: (0; 0), (0.5; 0.125), (1; 0.5), (1.5; 1.125), (2; 2), (3; 4.5).

Reproduction of a part of the function Y=0.5⋅X² by lines built on six points

Rationale and use cases

In this section, we will consider several cases where the calculation table saves the day.

The curve that describes the relationship between X and Y can be quite complex.

For example, using a fuel level sensor requires calibrating the fuel tank, and the shape of the chart built according to the calibration table will depend on the geometry of the tank, which is never ideal (it may have roundings, dents, internal stiffeners, and so on).

The chart based on the calibration table with small steps between measurements

It is problematic to describe such dependence in one formula. An easier way to describe this curve is to break it down into intervals where it behaves roughly like a straight line and determine the formulas for those lines. You can do it using XY pairs.

Reproduction of a complex curve by breaking it down into lines passing through eleven points

Also, sometimes the relationship between X and Y can vary over several intervals. To describe it, you need to use a system of several expressions, which cannot be done in the Parameter field in the sensor properties.

For example, some temperature sensors work as follows: X values in the range from 0 to 127 correspond to a positive temperature, and in the range from 128 to 255 — to a negative temperature. You will need a calculation table with two rows to handle such a case:

X=0; a=1; b=0
X=128; a=1; b=-256

The temperature chart where higher parameter values correspond to negative temperatures

Digital sensors are another prime example of a situation where the relationship between X and Y varies over several intervals. For example, an ignition sensor can be created based on a voltage parameter, and this requires two conditions taken into account: Y=0 when X<14 and Y=1 when X≥14. As we already know, this cannot be done using an expression in the sensor properties. But on the Calculation Table tab, this will require only two lines:

X=0; a=0; b=0
X=14; a=0; b=1

The ignition status chart depending on voltage

Oleg Zharkovsky,Customer Service Engineer 2023-02-21

Some trackers don't send information about fuel, or a unit is not equipped with fuel sensors, but users still want to see fuel consumption data in the report.

As an alternative to fuel sensors, you can use Consumption by rates, which is configured on the Advanced tab. Its calculation algorithm is simple: the mileage per interval is multiplied by the specified consumption rate (l/100 km), which may vary depending on the season. But in this article, we will cover another option for calculating fuel consumption without a sensor, which requires more explanation — Fuel consumption by math, aka Math consumption. Moreover, its field of application is not limited to one use case.

Where can you use math consumption?

First of all, math consumption is used in reports to compensate for the absence of fuel sensors or verify their readings. To display the results of a mathematical calculation, add the Consumed by math, Avg consumption by math columns, or other columns that have "by math" in their title to the table.

Math consumption is also used in fuel algorithms. Firstly, to detect fuel drains if the Calculate drains by time option is enabled. Secondly, to calculate the consumption on intervals with invalid values, if the Replace invalid values with math consumption option is enabled. Both mentioned options are in the additional settings of FLS.

How does math consumption work?

The system determines the expected consumption for an interval using a mathematical model. It is built on the basis of:

• engine operation sensors (ignition or absolute/relative engine hours) that indicate the fuel consumption rate at idle;
• engine efficiency sensors (EES), each of which indicates the influence of some factor on fuel consumption (engine rotation speed, temperature, axle load, air conditioning, attached equipment, and so on).

Math consumption per interval is the sum of consumptions between all messages on the interval. The following formula is used to calculate math consumption between the current message and the previous message:

Δt ⋅ ( C_{I 1} + C_{I 2} + ... + C_{I N} ) ⋅ (K_{EES 1} + (K_{EES 2} - 1) + (K_{EES 3} - 1) + ... + (K_{EES M} - 1)),

where Δt — the time between messages; C_{I j} — consumption rate at idle from the j-th engine operation sensor, which was enabled in the considered message; N — the number of engine operation sensors created in the unit; K_{EES i} — the value of the i-th engine efficiency sensor in the considered message; M — the number of engine efficiency sensors created in the unit.

Why bind engine operation sensors, engine efficiency sensors, and FLS?

Some units have several engines. In most cases, this is special-purpose machinery, and a concrete mixer truck is a good example: its main engine makes the vehicle move, and an additional autonomous engine rotates the mixing drum. Accelerating the vehicle or turning on the air conditioner may affect the fuel consumption of the main engine but will not affect the consumption of the additional one. Consequently, some factors affecting consumption (we take them into account using engine efficiency sensors) affect only one of the engines (we take them into account using engine operation sensors). At the same time, the unit may have several fuel tanks (we take them into account using FLS), which also need to be bound with a specific engine.

To bind mentioned sensors, you should enter the properties of the ignition sensor or absolute/relative engine hours sensors and select the appropriate engine efficiency sensors. Similarly, in the FLS properties, you can configure its binding with engine operation sensors.

How to quickly create a mathematical model?

To create a basic mathematical model, use Math Consumption Wizard located on the Sensors tab in the unit properties. In the Math Consumption Wizard window, you need to enter information about fuel consumption in different operating modes, as well as the seasonal coefficient and the season's start and end dates. Let's take a closer look at these fields:

• Fuel consumption (l/h) refers to consumption at idle, i.e., with the engine running and the vehicle not moving. The Min. moving speed is taken from the Trip Detector.
• Urban cycle and Suburban cycle (l/100 km) are standard vehicle characteristics you can find in documents, on the internet, or calculate in practice. At the same time, different countries use different approaches to defining these cycles. In Wialon, the urban cycle rate corresponds to a speed of 36 km/h, and the suburban one — 80 km/h.
• Seasonal coefficient (%) refers to the percentage increase in fuel consumption during the specified season compared to the rest of the year. You can disable the seasonal factor if there are no significant temperature changes throughout the year in the area where the vehicle is used.

By filling in Math Consumption Wizard, you will create a basic mathematical model that considers only the unit speed and seasonal influence. Such a model is approximate because, in practice, speed doesn't affect consumption — the engine rotation speed does, as well as the season doesn't affect consumption — the temperature does. However, by default, most trackers don't send information about engine rotation speed and temperature. That's why we've chosen a model that is suitable for all trackers.

It's impossible to automatically create a more accurate model, but you can do it manually by adding engine efficiency sensors.

How do engine efficiency sensors work?

The value of an engine efficiency sensor in each message should show how many times an influencing factor increases the consumption at idle compared to the consumption without the influence of this factor. For a better understanding, let's look at an example.

Let’s assume that the consumption at idle is 2 l/h, and when the heating system is turned on, the consumption increases to 2.2 l/h. Therefore, the ratio of these values is: 2.2/2 = 1.1
Let's also assume that the in4 parameter indicates the state of the heating system: if this parameter is equal to 0, the heating is off, and if it’s equal to 1, the heating is on.
In this case, to take into account the heating system influence on the consumption, you need to create a sensor with the Engine efficiency sensor type, specify in4 in the Parameter line, and add the following lines to the Calculation Table:

x = 0; a = 0; b = 1
x = 1; a = 0; b = 1.1

So, when the heating system is off, the engine efficiency sensor increases the consumption by 1 time (i.e., it doesn’t change it), and when the system is on, the consumption is increased by 1.1 times. Note that a zero value of the engine efficiency sensor would also not affect fuel consumption.

Using the method described above, you can take into account the influence of one factor on the expected consumption. If there are several engine efficiency sensors, all their values are taken into account simultaneously, forming the expected consumption rate on the interval between two messages (see the formula above).

How to make math consumption more accurate?

We should note that if you activate the Calculate drains by time option in the fuel level sensor properties, the system will compare math consumption with the FLS consumption. Unfortunately, the readings of the latter are not very accurate. Hence, there is no need to try to make an ideal mathematical model since this may not affect the result of comparison with FLS in the end.

However, you can try to increase the model accuracy in the following ways.

Consider more factors

You can create more engine efficiency sensors based on parameters from the tracker that describe factors affecting consumption.

Note that numerous factors influence consumption, but the degree of their influence may vary. For example, there’s probably no need to install an air humidity sensor, although humidity can also affect consumption. It makes more sense to measure tire pressure, but on the other hand, it’s better to avoid using under-inflated tires. But don't expect the high accuracy of the mathematical model if you ignore the cargo weight, which can be measured using an axle load sensor. In other words, you should choose the factors to consider according to the degree of their influence on the result.

Increase the accuracy of parameter measurement

This recommendation follows from the previous one. To improve the result, you can not only increase the number of sensors but also use higher accuracy sensors.

Increase the frequency of messages

If the factors influencing consumption change frequently, the tracker must also generate messages frequently; otherwise, you won’t be able to take all factors into account. For example, this applies to trips around the city, when a car can stand at several traffic lights within 10 minutes. But if only one message is recorded in the tracker's memory during this time, the mathematical model simply cannot take into account each speed change.

Why does math consumption show incorrect values?

There may be several reasons for such behavior.

1. The rates used in Math Consumption Wizard may differ from the actual ones (for example, due to the wear and tear of a vehicle). In this case, you can check their compliance with reality in practice.
2. This may be due to the incorrect setting of math consumption. Check that a non-zero value is specified in the Consumption, l/h line in the engine operation sensor properties. Also, make sure that the engine operation sensor and the engine efficiency sensor are bound.
3. The frequency of messages generated by the tracker may be too low.
4. This may be due to a breakdown of the sensor, which readings are used in the mathematical model.
5. In some cases, the system may think that the ignition was on all the time when the tracker didn’t send messages. In this case, the mathematical model will show that the engine should have been wasting fuel during all this time. To fix the situation, try to set the correct value of the Maximum interval between messages option on the Advanced tab in unit properties. You can achieve the same result using the Timeout option in the ignition sensor properties.

Oleg Zharkovsky,Customer Service Engineer 2022-02-04

This page only highlights the key differences between fuel algorithms. I don’t intend to list all possible combinations of settings from the fuel level sensor properties, although they all affect data processing to a certain extent. To study each option, I recommend watching a webinar or testing it in practice. Notice that you can change settings without worrying about the initial data because changing the fuel options doesn’t change messages but only affects the displayed result.

Which algorithm to choose

Below is a list of algorithm features that should help you make a choice.

Mileage-based algorithm

1. Suitable for most moving units.
2. Relatively easy to set up.
3. Used by default.

Time-based algorithm

1. Suitable
   
   • for stationary units,
   • for units with long idling intervals,
   • for units with vehicle attachments, which increases fuel consumption,
   • if you suspect fuel drains while driving,
   • if the mileage-based algorithm doesn’t produce expected results.
2. More difficult to set up.
3. For activation, it’s recommended to simultaneously enable the following options in the fuel level sensor properties:
   • Calculate fuel consumption by time
   • Calculate fillings by time
   • Calculate drains by time – to process drains, you also need a consumption mathematical model, which you can create, for example, using the Math Consumption Wizard.

What is the difference between algorithms?

First, we should note that, to some extent, a more correct name for the mileage-based algorithm would be a speed-based algorithm because it ignores messages in which speed is less than the Min moving speed set in the Trip detector. But since the mileage increases when moving, the current name is also appropriate.

It follows from the above that the key difference between algorithms is that the time-based algorithm analyzes all messages, while the mileage-based algorithm excludes some of the messages from the analysis, using simplification. It is based on the fact that you can assess the fuel level change during stops or parkings (i.e., on the low-speed interval) by two messages before and after a given stop or parking. For example, if a vehicle was in the parking lot from 14:00 to 16:00, and the fuel drain happened between 15:00-15:10, you can learn about the fact of drain simply by comparing fuel levels at 14:00 and 16:00.

Consumption

Both algorithms calculate consumption for an interval similarly: the fuel level value at the end of the interval is subtracted from the fuel level value at the beginning of the interval, and then the volume of fuel filling for this interval is added to them. However, the key difference between algorithms still implies that they take into account different intervals.

In addition, I’d like to note that the drain volume is included in the consumption by default until the Exclude drains from fuel consumption option is activated in the report template settings.

Fuel fillings

Detecting fillings is also the same for both algorithms: the system searches for messages with a sequential increase in the fuel level sensor readings. However, the mileage-based algorithm calculates fuel fillings during stops by only two points (fuel level at the end of the previous movement interval and at the beginning of the next one), without analyzing all messages for the given interval.

Fuel drains

Drain are detected using different methods:

• The mileage-based algorithm detects the drain during parking by two points (fuel level at the end of the previous movement interval and at the beginning of the next one), without analyzing all messages for the given interval.
• The time-based algorithm compares the actual consumption according to the fuel level sensor with the expected consumption determined by the mathematical model.

Oleg Zharkovsky,Customer Service Engineer 2021-12-08

If data received from the tracker meets all the drain detecting criteria, the Fuel Drains table will contain records about it, even if there was no actual drain. Such fuel drains are called false.

To correctly configure fuel drain detection, you need to know not only the technical features of Wialon algorithms but also the operating principles of hardware (trackers, sensors, and the unit's fuel system). This article provides simple instructions, following which you can eliminate false fuel drains by focusing on the fuel level chart only.

Required steps before applying instructions

• A unit is created in Wialon, data messages from the tracker are displayed in the system.
• The fuel level sensor is connected to the tracker, the fuel tank is calibrated.
• A sensor with the Fuel level sensor (FLS) type is created in the unit.
• The Calculate data by the sensor option is activated in the FLS settings.
• The calibration table (XY pairs) is added to the fuel level sensor Calculation table, whereafter the Generate button is clicked.
• A report template with a Regular type chart is created, which displays the Processed fuel level.
• The chart also displays fuel drain markers and the background of trips (it's pink by default), stops (blue), and engine hours (yellow).

Chart behavior in the location of false fuel drain

Choose one of the options below according to what you see on the chart where the fuel drain marker is located.

1. Jumps during motion or engine operation

During engine operation, driving on uneven surfaces or basically any movement, fuel fluctuations occur, and the FLS reads them. Depending on the tank volume and shape, as well as the FLS location, these fluctuations can reach dozens of liters, which can result in detected fuel drains. In general, you can compensate them with the help of a smoothing algorithm.

To do this, set filtration type to Adaptive median filtration in the fuel level sensor settings. In this case, the algorithm automatically calculates the appropriate value of filtration level.

As an alternative you can set filtration type to Median filtration to manually tune the smoothing algorithm. E.g. set the filtration level to 3. Keep in mind that high filtration levels should be used only with a high frequency of message sending (1-5 seconds between messages). After applying the filtration, fuel algorithms will work not with the raw data but with smoothed data.

To check if smoothing is effective, add the Fuel level line (before smoothing) to the chart and compare it with the Processed fuel level line (after smoothing). If the Processed fuel level line fluctuations still seem significant to you, try to increase the filtration level (an increment of 1 is recommended). But don't forget that smoothing may distort the input data, that's why you have to find the middle ground: Processed fuel level line fluctuations no longer seem significant (or they are eliminated), but at the same time, the lines before and after smoothing are still not much different in distinctive points (for example, during actual fillings/fuel drains).

2. A sharp jump immediately after the start or stop of motion

FLS readings can change abruptly at the moment of motion start/stop, which can result in fuel drain detection. If the chosen filtration level doesn't smooth out these jumps, and you don't want to increase it (for example, in your case, this causes significant distortion of input data at other intervals), then you can use one of the two time filters in the fuel level sensor settings:

• Ignore messages after the start of motion — this option allows you to exclude a specified number of seconds after starting the movement from the fuel drain analysis.
• Minimum stop duration to detect a fuel drain — if the duration of the interval without movement doesn't exceed the specified one, then this interval won't be analyzed for fuel drains (thus, you can cut off fuel level fluctuations, for example, during short stops at traffic lights).

3. Smooth falling with the running engine and no movement

There are two algorithms for fuel analysis in Wialon: the mileage-based algorithm (used by default) and the time-based algorithm. For stationary units and units with long idle intervals, it's recommended to use the time-based algorithm. To do this, activate three options in the fuel level sensor settings: Calculate fillings by time, Calculate drains by time, and Calculate fuel consumption by time. We should clarify that in this very case, it would be possible to do only with the Calculate drains by time option, but the simultaneous activation of all options will allow you to achieve better convergence of all fuel indicators in the reports.

When using the time-based algorithm, the FLS fuel consumption value is compared with the calculated fuel consumption value, i.e., with the value calculated by the mathematical model. At idle intervals, the calculated fuel consumption value is generally determined by the engine ignition sensor or engine hours counters. Therefore, open the ignition or engine hours sensor properties and check if the correct consumption rate per hour is set in the Consumption field.

4. Fuel drain during driving, although the chart looks normal

Most likely, you are using the time-based fuel analysis algorithm, and you've also activated the Detect fuel drain in motion option in the fuel level sensor settings. In this case, the FLS fuel consumption value is compared with the mathematically calculated consumption. If the consumption by calculation is set incorrectly, a false fuel drain can be detected when the unit is just making a trip; therefore, it's recommended to check the mathematical model of the calculated consumption. It's set via:

• engine ignition sensors or engine hours counters — in the properties in the Consumption field specify the consumption rate per hour at idle;
• engine efficiency sensors — this sensor can use any parameter that affects fuel consumption and based on its value, it determines the fuel consumption change coefficient, which is then multiplied with the consumption value from the previous point.

A basic mathematical consumption model can be created using the Math consumption wizard on the Sensors tab in the unit properties. This model includes the affect of speed and season on the consumption with a help of engine efficiency sensors. Further, you can complement this model, adding more engine efficiency sensors that take into account other factors affecting the consumption (cargo weight, temperature, operation of vehicle attachments, and so on).

5. Significant jumps to the minimum/maximum

If the chart shows jumps of the Processed fuel level line to 0 or to the maximum value (often 2¹⁶-1 = 65535) and back to the actual value, then even after applying the smoothing, these jumps can cause the detection of false drains. Such jumps in readings can be connected with the wrong configuration or the connection of the fuel level sensor itself.

It's recommended to fix this problem on the hardware side; however, on the Wialon side, you can try to cut off these readings using the Calculation table. To do this, go to the FLS settings, go to the Calculation table tab, and set the values of the Lower bound and/or the Upper bound corresponding to an empty and full tank. In the lower bound, however, it's better to set not 0 but a value close to zero (for example, 0.1) to cut off false jumps in readings to 0.

6. Significant jumps not to the minimum/maximum

If the FLS readings change by significant values (but not to 0 or the maximum value) and then return to the actual value, even after applying the smoothing, these jumps can cause the detection of false drains. Such behavior can be connected with voltage surges, which can be seen on the chart using the Voltage line if you have a Voltage sensor.

It's recommended to fix such situations on the hardware side; however, on the Wialon side, you can try to neutralize the impact via Validation. To do this, follow the instructions:

1. Open the Messages tab and request raw data messages for the interval that includes the considered fuel level jump.
2. Manually or using a filter, find another parameter that changes simultaneously with the FLS readings.
   Suppose this is the pwr_ext parameter, which for most trackers corresponds to the external voltage.
3. Determine, upon passing which value of the found parameter, the FLS readings change.
   Suppose that if pwr_ext is less than 12, then the FLS starts sending incorrect readings.
4. Enter the unit properties and create a sensor with the Custom digital sensor type using the parameter from point 3, and then define a Calculation table for it with the following lines:
   X = 0; a = 0; b = 0
   X = 12; a = 0; b = 1
5. Save the created sensor and the changes of unit properties by clicking OK twice.
6. Enter the unit properties again, and then the FLS properties. Specify the sensor from point 4 as a validator with the Not-null check type.

In the example above, a real case is considered since low voltage actually often leads to the distortion of readings of different sensors. This means there is a direct connection between the transmitted parameters of voltage and fuel level. However, you can also use a correlation if you notice a simultaneous change in the FLS readings and any other parameter. Perhaps the tracker doesn't send a voltage value, but it does send a temperature value, and the temperature sensor also fails and sends, for example, 451 °F at the moment of a power surge. In this case, using validation, try to connect the FLS and the temperature value, which should also correct the situation.

7. Smooth falling after filling when there are several interconnected tanks with an FLS in each

Such a change in the FLS readings may be because the unit has several interconnected tanks and fuel flows between them. After filling one of the tanks, the equalization of levels between several tanks may take some time. If you created fuel level sensors in Wialon separately, the system can detect false drain in one of the tanks immediately after filling.

When working with several interconnected tanks, we recommend you to create a Custom sensor for each FLS (for example, named “FLS 1” and “FLS 2”) and add your calibration table into them. After that, create a separate sensor with the Fuel level sensor type, don't add the calibration table into it, but instead just use the following formula: [FLS 1]+[FLS 2]

8. Sharp falling when reaching a certain level

This situation can be observed for tanks of a specific shape at the moment of transition from a wide part to a narrow one (for example, L-shaped tanks). This is particularly likely if the calibration was performed using too few points, and often it's done using only two points (for an empty and full tank). Therefore, it makes sense to re-calibrate the tank using small portions.

9. Smooth change at the same time

Sometimes the fuel level drops/rises at specific points in time, and in some cases, later even returns to the actual value. This can happen at night, or during a trip (especially when loaded), or after approximately equal time after the end of the trip — it's difficult to identify a common rule.

Possible reasons:

• temperature change, affecting the fuel volume and the tank deformation (this is especially true for flexible plastic tanks);
• a "vacuum" created due to the pressure difference (active intake of fuel into the engine);
• sedimentation of impurities in the fuel or dirt in the tank, happening after the end of the trip (shaking).

The solution in most cases is related to the hardware: using a fuel tank cap with a valve to equalize pressure, dirt/sediment removal in the tank or on the FLS. However, if the situation is related only to temperature changes, then using a sensor with the Temperature coefficient type can help you (you can find an example of its setting in the documentation).

Oleg Zharkovsky,Customer Service Engineer 2024-02-12

SDK (Software Development Kit) is a set of tools for developing custom applications. Wialon SDK includes several APIs. The most basic of them is the Remote API, and these articles are focused on studying this exact tool. Remote API allows access to data through HTTP requests and is relevant for 1C, PHP, C++/C#, and other programming languages. JS API and others are built on top of the Remote API.

This article will cover the basic knowledge necessary for beginners to use Remote API.

Viewing Requests in the Browser

When starting to explore the SDK, it is often necessary to understand which API request is being sent to the server when performing a certain action in the Wialon interface. This can be easily tracked using built-in browser tools for network request monitoring.

In Chrome browser, you can do it using the Network tab in the Developer Tools, which can be opened by pressing F12. In other browsers, this tool may open differently, as described in the browser's documentation.

When viewing network requests, you can see the sent request, its parameters, and the response from the API server in JSON format.

Request Format

HTTP requests are sent to the server in the following format:

https://host/wialon/ajax.html?svc=REQUEST_NAME¶ms={PARAMETERS}&sid=SESSION_IDENTIFIER

Obtaining a Token and Authorization

Wialon uses a token for authorization, which is a key used for encrypted user identification.

To create a token, you can use the oAuth form. After you log in successfully, the token will be displayed in the browser's address bar as the value of the access_token parameter. It is important here to consider additional parameters that regulate properties such as token duration (duration parameter), user name (user parameter), token flags (access_type parameter), and others.

Example of an extended form for obtaining a token:

https://hosting.wialon.com/login.html?client_id=APP_NAME&access_type=256&activation_time=0&duration=0&lang=en&flags=0&user=USER_NAME

Example of a response:

https://hosting.wialon.com/login.html?lang=en&user=USER_NAME&wialon_sdk_url=https%3A%2F%2Fhst%2Dapi%2Ewialon%2Ecom&access_token=TOKEN_VALUE&svc_error=0

After obtaining the token, you can use it for authorization. Here is the example of logging in with a token:

https://hst-api.wialon.com/wialon/ajax.html?svc=token/login¶ms={"token":"TOKEN_VALUE"}

The response to the token login contains the eid parameter, and its value is the unique session identifier. It will be used in almost all API requests.

Setting the Time Zone

By default, when working with the Remote API, data is displayed according to the GMT+0 time zone. To change it to the desired time zone, the render/set_locale request is used. It is sufficient to execute this request within one active session.

When sending the render/set_locale request, you must use the tzOffset parameter. The standard method for calculating its value is described in the documentation.

You can also find out the required value of the tzOffset parameter by viewing network requests while changing the user's time zone in the web interface.

System ID

In the API, work with almost every item is done through system IDs, which are represented by unique numerical values.

System IDs are not displayed in web interfaces by default but they can be seen in three ways:

1. In the response to a request for searching items by property (core/search_items). We will explain it in more detail in the next section of this article.
   
2. In the parameters of requests when viewing network requests in the browser.

3. In the avl_id column in the management system.

   To make the avl_id column shown, you need to log in to the CMS and add ?features=avl_id to the end of the link. An example of such a link is shown in the image below.
   
   

Search Items by Property

This request allows you to find items by certain properties.

The search is performed for the following types of items, which are specified in the itemsType field:

• avl_hw — hardware type;
  
• avl_resource — resource;
  
• avl_retranslator — retranslator;
  
• avl_unit — unit;
  
• avl_unit_group — unit group;
  
• user — user;
  
• avl_route — route.
  

One of the possible search properties can be subitems. In this case, the propType parameter is set to propitemname, and the propName parameter takes the following values:

• units:
  
  • unit_sensors — sensors;
  • unit_commands — commands;
  • service_intervals — service intervals;
    
    
• resources:
  
  • drivers — drivers;
  • driver_groups — driver groups;
  • jobs — jobs;
  • notifications — notifications;
  • trailers — trailers;
  • trailer_groups — trailer groups;
  • zones_library — geofences;
  • reporttemplates — report templates;
  • orders — orders;
    
    
• routes:
  
  • rounds — rounds;
  • route_schedules — schedules;
    
    
• retranslators:
  
  • retranslator_units — retranslator units;
    
    
• units, users, or resources:
  
  • custom_fields — custom fields;
  • admin_fields — administrative fields.

The information in the response depends on the flags specified in the search request in the flags parameter. Flags are specified in DEC format.

Let's consider several examples of using the request for searching items by property (other examples can be found in the documentation).

Search Items by a Specific Name

In case you need to get a list of all units available to the user with the word Tractor in their name, as well as information about the sensors created in these units, you can use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"sys_name","propValueMask":"*Tractor*","sortType":"sys_name"},"force":1,"flags":4097,"from":0,"to":0}&sid=SESSION_IDENTIFIER

{
	"searchSpec":{
		"itemsType":"avl_unit",
		"propName":"sys_name",
		"propValueMask":"*Tractor*",
		"sortType":"sys_name",
		"propType":"",
		"or_logic":"0"
	},
	"dataFlags":4097,
	"totalItemsCount":1,
	"indexFrom":0,
	"indexTo":0,
	"items":[
		{
			"nm":"Tractor 1",
			"cls":2,
			"id":22353120,
			"mu":0,
			"sens":{
				"1":{
					"id":1,
					"n":"Ignition",
					"t":"engine operation",
					"d":"",
					"m":"On\/Off",
					"p":"in1",
					"f":0,
					"c":"{\"act\":1,\"appear_in_popup\":true,\"ci\":{},\"cm\":1,\"mu\":0,\"pos\":2,\"show_time\":false,\"timeout\":0}",
					"vt":0,
					"vs":0,
					"tbl":[]
				},
				"2":{
					"id":2,
					"n":"Fuel level",
					"t":"fuel level",
					"d":"",
					"m":"l",
					"p":"adc1",
					"f":0,
					"c":"{\"act\":1,\"appear_in_popup\":true,\"calc_fuel\":0,\"ci\":{},\"cm\":1,\"fuel_params\":{\"fillingsJoinInterval\":300,\"filterQuality\":0,\"flags\":0,\"ignoreStayTimeout\":10,\"minFillingVolume\":20,\"minTheftTimeout\":0,\"minTheftVolume\":10,\"theftsJoinInterval\":300},\"mu\":0,\"pos\":1,\"show_time\":false,\"timeout\":0}",
					"vt":0,
					"vs":0,
					"tbl":[]
				}
			},
			"sens_max":-1,
			"uacl":-1
		}
	]
}

Search Users Created after a Specific Date

Imagine you need to get a list of users created after February 23, 2021, 05:41:46 (GMT+0). The response should contain user's system IDs and email addresses.

In such a case use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"user","propName":"rel_creation_time","propValueMask":">=1614058906","sortType":"sys_name"},"force":1,"flags":3,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Search Units of a Specific Type

Let’s get a list of units with the Wialon Retranslator hardware type that have sent messages after February 12, 2023, 12:00:00 (GMT+0). The response must display information about the sensors on the units, the last message date, and the position. In this case, use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propName":"rel_hw_type_name,rel_last_msg_date","propValueMask":"Wialon%20Retranslator,>1676203200","sortType":"rel_creation_time"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Search Units by Sensor Name

To get a list of units that have a sensor named Engine created, you can use the following request:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit","propType":"propitemname","propName":"unit_sensors","propValueMask":"Engine","sortType":"sys_name"},"force":1,"flags":1,"from":0,"to":0}&sid=SESSION_IDENTIFIER

Search Unit Groups by Multiple Properties

To get a list of unit groups created by User and containing more than 5 units, the following request can be used:

https://hst-api.wialon.com/wialon/ajax.html?svc=core/search_items¶ms={"spec":{"itemsType":"avl_unit_group","propName":"rel_user_creator_name,rel_group_unit_count","propValueMask":"User,>5","sortType":"sys_name"},"force":1,"flags":133,"from":0,"to":0}&sid=SESSION_IDENTIFIER

List of Common Errors

An error is displayed when it is not possible to execute a request. A complete list of returned errors can be found in the documentation.

The most common errors are the following:

• {error: 1} — invalid session.
  This error is displayed when the unique session identifier has expired. To fix this error, simply log in with the token again and use the new session identifier (sid) for further requests.

  If within 5 minutes no request is made within the session, then it becomes inactive. To keep the session active, you can send an avl_evts request every 5 minutes.

• {error: 4} — invalid input.
  This error is displayed if there is a mistake in the request text, for example, not all required parameters are specified, text parameters are not enclosed in quotes, there is no opening or closing bracket, etc. To fix this error, correct the text of the executed request according to its description in the documentation.
  
  
• {error: 7} — access denied.
  This error is displayed if the user does not have sufficient access flags to execute the request. To fix this error, check if the token used to obtain the unique session identifier has sufficient access flags, as well as if the user the token was generated for has sufficient access rights regarding the used items.
  

Ekaterina Grib,Customer Service Engineer 2023-08-02